Release 10.1A: OpenEdge Development:
Progress 4GL Handbook

Object handles

You’ve seen a few examples of the use of handles in earlier chapters. You can define a variable to hold the handle of an object with the DEFINE VARIABLE statement:

DEFINE VARIABLE handle-name AS HANDLE [ NO-UNDO ].

You can also define temp-table fields as type HANDLE, so it would be possible to assign the handle of an object to a field in a temp-table record.

As you can see from the CREATE statement syntax, the only way to identify a dynamic object is to associate it with a handle. It does not have a name as a static object does. Progress builds a data structure to the object when it executes the CREATE statement and the handle becomes a pointer to that structure. You retrieve or set attribute values through the handle, and execute methods on the object through the handle. In Chapter 8, "Defining Graphical Objects," you learned how to use attributes and methods by appending a colon and the attribute or method name to the object name, such as in the expression bMyButton:LABEL. For dynamic objects you do the same thing with the object’s handle, as shown in this sequence:

DEFINE VARIABLE hButton AS HANDLE     NO-UNDO. CREATE BUTTON hButton ASSIGN LABEL = "Test Button". MESSAGE "Label: " hButton:LABEL SKIP         "Type: " hButton:TYPE SKIP         "Handle:" hButton:HANDLE SKIP         "Dynamic?: " hButton:DYNAMIC          VIEW-AS ALERT-BOX.

Figure 18–1 shows the result.

Figure 18–1: Test button message

As you can see, the handle can be represented as an integer value, but you cannot do any kind of arithmetic with object handles or manipulate handle values in any other way.

Each handle value represents a unique instance of the object you create. As you learned in Chapter 8, "Defining Graphical Objects,"when you use the DEFINE statement to define a static object, it does not have a unique identity until it is realized. Depending on how it is realized, the same object definition can have multiple distinct run-time instances. A handle always points to a single unique instance of an object.